<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Karamelo: Getting started</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { init_search(); });
</script>
<script type="text/x-mathjax-config">
  MathJax.Hub.Config({
    extensions: ["tex2jax.js", "TeX/AMSmath.js", "TeX/AMSsymbols.js"],
    jax: ["input/TeX","output/HTML-CSS"],
});
</script><script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-MML-AM_CHTML/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="karamelodoxy.css" rel="stylesheet" type="text/css">
<!--  -->
<script type="text/javascript" src="karamelo_navtree_hacks.js"></script>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><a href="http://www.karamelo.org"><img alt="Logo" src="Karamelo_logo.png"/></a></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname"><a href="http://www.karamelo.org">Karamelo</a>
   &#160;<span id="projectnumber">714599e9</span>
   </div>
   <div id="projectbrief">Parallel Material Point Method Simulator</div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('GettingStarted.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Getting started </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This is a very short guide on how to get started with <b>Karamelo</b>.</p>
<h1><a class="anchor" id="GettingStartedInstallation"></a>
How to install Karamelo?</h1>
<p>In order to use <b>Karamelo</b>, you need to download, extract and compile <b>Karamelo</b>'s source code. Compiling is no that complicated thanks to the use of CMake (<a href="https://cmake.org/">cmake.org</a>). It will automatically check for most dependencies, but unfortunately not all of them.</p>
<h2><a class="anchor" id="Dependencies"></a>
Dependencies</h2>
<p><b>Karamelo</b> has a few dependencies that need to be satisfied for it to successfully compile and run. They are: </p><ul>
<li>
<a href="https://cmake.org/">Cmake</a> </li>
<li>
MPI. It was tested with OpenMPI </li>
<li>
<a href="http://eigen.tuxfamily.org/index.php?title=Main_Page">Eigen</a> version 3  </li>
<li>
<a href="http://www.boost.org/">Boost</a> which can be easily installed with the package manager of every Linux distribution. </li>
<li>
Python 3 with <a href="https://matplotlib.org/">Matplotlib</a> </li>
<li>
<a href="https://github.com/lava/matplotlib-cpp">matplotlib-cpp</a> which allows the use of the Matplotlib library directly from C++.<br />
<b>Remark</b>: a bug was detected that prevent versions of matplotlib-cpp earlier than <em>f4ad842e</em> to be used with Karamelo. </li>
<li>
<a href="https://www.cs.unc.edu/Research/compgeom/gzstream/">gzstream</a> which is used to compress dump files. </li>
</ul>
<h2><a class="anchor" id="InstallUbuntu"></a>
Installing Karamelo on Ubuntu</h2>
<p>The authors, as many researchers that do simulation work use Linux, and Ubuntu in particular. In order to make it simple for people like us to install and run Karamelo on Ubuntu, here are the steps to follow to download, build, and run the last version of the code. The following steps were tested using the versions 18.04 LTS and 16.04 LTS.</p>
<ol>
<li>
Install all the dependencies shipped with ubuntu: <div class="fragment"><div class="line">sudo apt install make gcc g++ libz-dev cmake libopenmpi-dev libeigen3-dev libboost-dev python-dev python-matplotlib</div></div><!-- fragment --> </li>
<li>
Download and install the extra external dependencies: <ol>
<li>
Matplotlib-cpp: <div class="fragment"><div class="line">git clone https:<span class="comment">//github.com/lava/matplotlib-cpp.git </span></div></div><!-- fragment --> Matplotlib-cpp being just a collection of headers, there is nothing to compile. However, one needs to celect the right commit that allows karamelo to run without problems. More recent commits have been found to be buggy: <div class="fragment"><div class="line">cd matplotlib-cpp/</div><div class="line">git checkout f4ad842e</div></div><!-- fragment --> </li>
<li>
Download gzstream and compile it. </li>
</ol>
</li>
<li>
<p class="startli">Add the path to Eigen, gzstream and matplotlib to your paths: Add to your .bash_profile: </p><div class="fragment"><div class="line">CPATH=$CPATH:/usr/include/eigen3:/home/toto/gzstream:/home/toto/matplotlib-cpp:/usr/include/python2.7</div><div class="line">export CPATH</div><div class="line"></div><div class="line">LIBRARY_PATH=$LIBRARY_PATH:/usr/include/eigen3:/home/toto/gzstream:/home/toto/matplotlib-cpp:/usr/include/python2.7</div><div class="line">export LIBRARY_PATH</div></div><!-- fragment --><p class="endli"><b>Remark</b>: change /home/toto/ to the path to the root directory where you have installed gzstream and matplotlib-cpp (they can be different from each other). </p>
</li>
<li>
<p class="startli">Download and install Karamelo:</p>
<div class="fragment"><div class="line">git clone https:<span class="comment">//github.com/adevaucorbeil/karamelo.git</span></div><div class="line">cd ~/karamelo</div><div class="line">cmake -DCMAKE_BUILD_TYPE=release build .</div><div class="line">make</div></div><!-- fragment --><p class="endli"></p>
</li>
<li>
Enjoy! </li>
</ol>
<h1><a class="anchor" id="GettingStartedFirstExample"></a>
A simple first example</h1>
<p>Here is a simple example of two disks bouncing onto each other to get you started with <b>Karamelo</b>.</p>
<h2><a class="anchor" id="ExampleSetup"></a>
Setup</h2>
<p>This example involves two elastic disks launched at a speed 0.1 mm/s towards each other:</p>
<div class="image">
<img src="two-disks.png" alt="two-disks.png"/>
</div>
<h2><a class="anchor" id="ExampleInputFile"></a>
Input file</h2>
<p>In order to simulate this problem, we need to create an input file that we called two-disks.mpm which reads:</p>
<div class="fragment"><div class="line">#####################################################</div><div class="line">#               UNITS: MPa, mm, s                   #</div><div class="line">#####################################################</div><div class="line">E   = 1e+3</div><div class="line">nu  = 0.3</div><div class="line">rho = 1000</div><div class="line">K      = E/(3*(1-2*nu))</div><div class="line">mu     = E/(2*(1+nu))</div><div class="line">lambda = E*nu/((1+nu)*(1-2*nu))</div><div class="line">c      = sqrt(E/rho)</div><div class="line">L    = 1</div><div class="line">hL   = 0.5*L</div><div class="line">A_zy = L*L</div><div class="line">FLIP=1.0</div><div class="line">#---------- SET METHOD --------------#</div><div class="line">method(ulmpm, FLIP, linear, FLIP)</div><div class="line">N        = 20     # 20 cells per direction</div><div class="line">cellsize = L/N    # cell size</div><div class="line"># 2D problem, which the computational domain is</div><div class="line">dimension(2,-hL, hL, -hL, hL, cellsize)</div><div class="line"># solids (2 balls)</div><div class="line">R = 0.2</div><div class="line">region(rBall1, cylinder, -hL+R, -hL+R, R)</div><div class="line">region(rBall2, cylinder, hL-R, hL-R, R)</div><div class="line">material(mat1, linear, rho, E, nu)</div><div class="line"></div><div class="line">#---------- SET SOLID --------------#</div><div class="line">ppc1d = 2</div><div class="line">solid(sBall1, region, rBall1, ppc1d, mat1, cellsize,0)</div><div class="line">solid(sBall2, region, rBall2, ppc1d, mat1, cellsize,0)</div><div class="line"></div><div class="line">#---------- IMPOSE INITIAL CONDITIONS --------------#</div><div class="line">group(gBall1, particles, region, rBall1, solid, sBall1)</div><div class="line">group(gBall2, particles, region, rBall2, solid, sBall2)</div><div class="line">v = 0.1</div><div class="line">fix(v0Ball1, initial_velocity_particles, gBall1, v, v, NULL)</div><div class="line">fix(v0Ball2, initial_velocity_particles, gBall2, -v, -v, NULL)</div><div class="line"></div><div class="line">#-----------OUTPUT-------------------------------------#</div><div class="line">N_log = 50</div><div class="line">dumping_interval = N_log*1</div><div class="line">dump(dump1, all, particle, dumping_interval, dump_p.*.LAMMPS, x, y, z)</div><div class="line">dump(dump2, all, grid, dumping_interval, dump_g.*.LAMMPS, x, y, z)</div><div class="line"></div><div class="line">fix(Ek, kinetic_energy, all)</div><div class="line">fix(Es, strain_energy, all)</div><div class="line">Etot = Ek_s + Es_s</div><div class="line"></div><div class="line">#----------- RUN --------------------#</div><div class="line">set_dt(0.001)</div><div class="line"></div><div class="line">log_modify(custom, step, dt, time, Ek_s, Es_s)</div><div class="line">plot(Ek, N_log, time, Ek_s)</div><div class="line">plot(Es, N_log, time, Es_s)</div><div class="line">plot(Etot, N_log, time, Etot)</div><div class="line">save_plot(plot.pdf)</div><div class="line"></div><div class="line">set_output(N_log)</div><div class="line"></div><div class="line">run_time(3.5)</div><div class="line"></div></div><!-- fragment --><h2><a class="anchor" id="RunningExample"></a>
Running</h2>
<p>In order to run this example, on 4 CPUs, for instance, simply execute the following command: </p><div class="fragment"><div class="line">NUM_CPU = 4</div><div class="line">mpirun -np ${NUM_CPU} /path/to/karamelo/directory/karamelo -i two-disks.mpm</div></div><!-- fragment --><p>Of course, you can change the number of CPU by adjusting the variable NUM_CPU.</p>
<h2><a class="anchor" id="Results"></a>
Results</h2>
<p>This example generates three types of results: </p><ol>
<li>
A log file called log.mpm<br />
The data displayed in this file are specified by the command: <div class="fragment"><div class="line">log_modify(custom, step, dt, time, Ek_s, Es_s)</div></div><!-- fragment --> Therefore, here they are, in order: the step (step), the timestep (dt), the overall time (time), the total kinetic energy (Ek_s) and the total strain energy (Es_s) </li>
<li>
Two series of dump files called dump_p.*.LAMMPS and dump_g.*.LAMMPS to be visualized with <a href="http://www.ovito.org">Ovito</a>. The first series contains particles data, the second, grid nodes data. They are generated by the following commands:<br />
<div class="fragment"><div class="line">dump(dump1, all, particle, dumping_interval, dump_p.*.LAMMPS, x, y, z)</div><div class="line">dump(dump2, all, grid, dumping_interval, dump_g.*.LAMMPS, x, y, z)</div></div><!-- fragment --> </li>
<li>
A plot of the kinetic, strain, and total energies, saved as "plot.pdf". This is obtained with the following commands:<br />
<div class="fragment"><div class="line">plot(Ek, N_log, time, Ek_s)</div><div class="line">plot(Es, N_log, time, Es_s)</div><div class="line">plot(Etot, N_log, time, Etot)</div><div class="line">save_plot(plot.pdf)</div></div><!-- fragment --> </li>
</ol>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Tue Jul 7 2020 22:31:23 for Karamelo by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.13 </li>
  </ul>
</div>
<!-- Matomo -->
<script type="text/javascript">
  var _paq = _paq || [];
  /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="//stats.sylphide-consulting.com/matomo/";
    _paq.push(['setTrackerUrl', u+'piwik.php']);
    _paq.push(['setSiteId', '20']);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s);
  })();
</script>
<noscript><p><img src="//stats.sylphide-consulting.com/matomo/piwik.php?idsite=20&rec=1" style="border:0;" alt="" /></p></noscript>
<!-- End Matomo Code -->
</body>
</html>
